Patch Deployment Templates

When deploying patches to machines, patch deployment templates allow you to specify a number of different options. For example, you can specify whether the deployment target should be restarted after the deployment, how fast the patches should be copied to the remote machines, whether reports should be sent, and much more.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

Supported Requests

Method	URL	Input	Return
DELETE	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}		Success or failure code. You cannot delete a predefined template.
GET	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates	URL Parameters	PatchDeploymentTemplates[]
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template guid}		PatchDeployTemplate
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/customactions		CustomActions[]
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/customactions/{custom action id}		CustomAction
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/usedby		Usedby[]
POST	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates	Request Body

Input Models

URL Parameters

Name	Type	Description
count	Integer	Provide the count of items to return. The default is 10 and the maximum value is 1000.
createdByMe	Boolean	Returns only those items created by the user. This parameter will be removed in a future release and should only be used in legacy requests.
name	String	Returns the items whose name matches the specified name.
start	Integer	Sets the starting point. The items are sorted by their unique identifier and the starting point is the index into that sorted list.
path	String	Sets the path and is used to find templates matching the specified path.

Request Body

Name	Required?	Type	Default Value	Description
description	No	String	None	Gets or sets the description.
distributionServerOptions	No	DistributionServerOptions		The options corresponding to the Distribution Servers tab of the deployment template.
generalOptions	No	DeployGeneralOptions		The options corresponding to the General tab of the deployment template.
name	Yes	String	None	Gets or sets the name.
path	No	String	None	Gets or sets the path.
postDeploymentReboot	No	PostDeployReboot		The options corresponding to the Post-deploy Reboot tab of the deployment template.
preDeploymentReboot	No	PreDeployReboot		The options corresponding to the Pre-deploy Reboot tab of the deployment template.
virtualOptions	No	VirtualMachineAndTemplate Options		The options corresponding to the Hosted VMs/Templates tab of the deployment template.

Example with Sample Response

Create a patch deployment template named "Sample"

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

Request Body

{"Name":"Sample","Description":"A sample deployment template created using the REST API"}

Sample Response

Copy

{
    "creator": "SHAVLIK\\joe.coder",
    "description": "A sample deployment template created using the REST API",
    "generalOptions": {
        "removeTempFiles": false,
        "sendTrackerMessages": true,
        "shutdownIis": false,
        "shutdownSql": false
    },
    "id": "9b5d4668-48fa-41ed-b424-094e6922a11b",
    "isSystem": false,
    "isTemporary": false,
    "links": {
        "customactions": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b/customactions"
        },
        "self": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b"
        },
        "usedby": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b/usedby"
        }
    },
    "name": "Sample",
    "postDeploymentReboot": {
        "options": {
            "powerState": "Restart",
            "countdownMinutes": 5,
            "extendMinutes": 1,
            "forceActionAfterMinutes": 10,
            "loggedOnUserAction": "ForceActionAfterMinutes",
            "systemDialogSeconds": 60,
            "userOptions": "AllowExtension"
        },
        "when": "Immediate"
    },
    "preDeploymentReboot": {
        "when": "NoReboot"
    },
    "virtualOptions": {
        "takePostDeploymentSnapshots": false,
        "takePreDeploymentSnapshots": false
    }
}

Other Request Examples

Add a patch deployment template with a name of Sample with pre-deployment options specified

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

{ name: "Example5", PreDeploymentReboot = @{ When ='Immediate'; Options = @{ LoggedOnUserAction = 'ForceActionAfterMinutes'; ForceActionAfterMinutes=15; extendMinutes = 1; userOptions='AllowExtension, AllowCancelTimeout, AllowCancelReboot' } }; }

Output Models

PatchDeployTemplate

Name	Type	Description
creator	String	The creator.
description	String	Gets or sets the description.
distributionServerOptions	DistributionServerOptions	The options corresponding to the Distribution Servers tab of the deployment template.
generalOptions	DeployGeneralOptions	The options corresponding to the General tab of the deployment template.
id	Guid	Gets or sets the patch deployment template UID.
isSystem	Boolean	Gets or sets the flag indicating if this is a system template.
isTemporary	Boolean	Indicates that this is temporary and can be deleted after the deployment.
links	Links	Shows the related URLs for the patch deployment template, the custom actions and the usedby list.
name	String	Gets or sets the name.
path	String	Gets or sets the path.
postDeploymentReboot	PostDeployReboot	The options corresponding to the Post-deploy Reboot tab of the deployment template.
preDeploymentReboot	PreDeployReboot	The options corresponding to the Pre-deploy Reboot tab of the deployment template.
virtualOptions	VirtualMachineAndTemplate Options	The options corresponding to the Hosted VMs/Templates tab of the deployment template.

DeployGeneralOptions

Name	Type	Description
hoursUntilEmailSent	Integer	Indicates how many hours to wait for patches to be successfully deployed before sending any automatic email messages.
remoteDialogConfig	RemoteDialogConfig	The options corresponding to the Remote Dialog section on the General tab of the deployment template.
removeTempFiles	Boolean	Indicates if the temporary patch files that were copied during the deployment process will be removed.
sendTrackerMessages	Boolean	Indicates if Deployment Tracker status messages will be sent from the machines being patched.
shutdownIis	Boolean	Indicates if the IIS Server will be shut down before the patch deployment process begins.
shutdownSql	Boolean	Indicates if the SQL Server will be shut down before the patch deployment process begins.

RemoteDialogConfig

Name	Type	Description
caption	String	Specifies the text you want to appear in the Remote dialog caption.
title	String	Specifies the text you want to appear in the Remote dialog box title.

DistributionServerOptions

Name	Type	Description
byIpRange	Boolean	Indicates if the distribution server that will be used will be determined by the IP address of each target machine. You must have defined one or more IP ranges and assigned the ranges to a primary distribution server and to a backup server.
defaultId	Integer	The default distribution server ID when UseSpecificServer is specified.
errorRetry	RelayErrorRetry[]	Specifies when to try again if no patch can be retrieved from the distribution server.
fallbackToVendorSite	Boolean	If the distribution server is not available, the machine being patched will attempt to download the patch files from the patch vendor's website.
staggerStartTime	Integer	Stagger distribution server download times in minutes.

RelayErrorRetry

Name	Type	Description
none	String	A retry will not be attempted and the deployment will fail.
atReboot	String	A retry will be attempted each time the target machine is rebooted, for up to three reboots.
periodic	String	A retry will be attempted at 15, 30, 60 and 120 minute intervals after the initial failure, and again when the target machine is rebooted. Retries are also attempted after two subsequent reboots.

PostDeployReboot

Name	Type	Description
options	PostDeployRebootOptions	Specifies the reboot options.
when	RebootWhenOption	Specifies when the reboot will occur.

PreDeployReboot

Name	Type	Description
options	DeployRebootOptions	Specifies the reboot options.
when	RebootWhenOption	Specifies when the reboot will occur.

PostDeployRebootOptions

Name	Type	Description
earliestTime	DateTime	The earliest time the safe reboot action can occur.
powerState	TargetPowerState	The target power state after deployment is complete.

TargetPowerState

Enables you to specify what state you want to leave the machines after the reboot. The items in this table are mutually exclusive; you can only specify one option.

Name	Type	Description
stayOnline	String	The machines are kept in their current state.
sleep	String	The machines are put into sleep mode.
hibernate	String	The machines are put into a hibernation mode.
shutdown	String	The machines are powered off without being restarted.
restart	String	The machines are restarted and left in a powered on state.
restartThenSleep	String	The machines are restarted and then put into sleep mode.
restartThenHibernate	String	The machines are restarted and then put into a hibernation state.
restartThenShutdown	String	The machines are restarted and then powered off.

RebootWhenOption

Name	Type	Description
noReboot	String	Do not reboot the machine after patch deployment.
immediate	String	Reboot the machine immediately after deployment.
scheduledTime	String	Reboot the machine at the next occurrence of the scheduled time.
scheduledDateTime	String	Reboot the machine at the scheduled date and time.
immediateIfRequired	String	Reboot the machine immediately, but only if required.
scheduledTimeIfRequired	String	Reboot the machine at the scheduled time, but only if required.
scheduledDateTimeIfRequired	String	Reboot the machine at the scheduled date and time, but only if required.

DeployRebootOptions

Name	Type	Description
countDownMinutes	Integer	The countdown minutes.
extendMinutes	Integer	The number of minutes a user is allowed to extend the countdown.
forceActionAfterMinutes	Integer	The number of minutes before the safe reboot option action will occur.
forceActionOnLatestTime	DateTime	The latest time the safe reboot action will occur.
loggedOnUserAction	LoggedOnUserAction[]	The action to take if a user is logged on.
systemDialogSeconds	Integer	The number of seconds the system dialog will display during shutdown.
userOptions	RebootInteractionOptions[]	The options a user is allowed to do during the safe reboot action.

RebootInteractionOptions

If you elect to restart machines, you can specify the degree of control the user will have over the restart process. These are flags, so you can add several of them at once in an array.

Name	Description
none	The user will have no control over the restart process.
allowExtension	Allow the user to extend the time-out countdown up to a specified maximum.
allowCancelTimeout	Allow the user to cancel the time-out. The patches will not be deployed until the user manually restarts the machine.
allowCancelReboot	Allow the user to cancel the reboot. The patches will not be installed until the machine is restarted.
allowNoTimeout
noRestart

LoggedOnUserAction

If you elect to restart machines, you can specify the amount of warning that a logged-on user will receive.

Name	Description
alertUser	Alert the user that a restart will occur when they log off.
forceActionAfterMinutes	Force a restart after a number of minutes have passed.
forceActionOn	Force a restart at a specific date and time.

VirtualMachineAndTemplateOptions

Name	Type	Description
maxSnapshotCount	Integer	The maximum snapshot count to manage.
oldestSnapshotInDays	Integer	The number of days a snapshot will be allowed to exist.
takePostDeploymentSnapshots	Boolean	Indicates if a snapshot will be taken of the offline virtual machine after deploying missing patches or service packs.
takePreDeploymentSnapshots	Boolean	Indicates if a snapshot will be taken of the virtual machine prior to deploying missing patches or service packs.

CustomAction

Name	Type	Description
actionType	CustomDeploymentAction[]	Specifies the action type.
command	String	The location of the .exe file that is to be executed.
id	Integer	The unique identifier of this CustomAction object.
kb	String	The KB number.
links	Links	Shows the related URLs
patchActedOn	String	The patch that will be acted on during installation.

CustomDeploymentAction

Specifies when during the patch deployment process the custom command will be triggered.

Name	Description
push	Pushes a custom batch file or custom executable file to the target machines as part of the deployment.
first	Before any patches are installed.
before	Before each patch or service pack is installed.
after	After each patch or service pack is installed.
last	After all patches are installed (but before reboot)
reboot	After the reboot.

UsedBy

Name	Type	Description
name	String	The name of the item using the template.
usageType	Enum	The type of component using the template.

Patch Deployment Templates

Base URL

Supported Requests

Input Models

Example with Sample Response

Create a patch deployment template named "Sample"

POST Request

Request Body

Sample Response

Other Request Examples

DELETE Request

GET Request

GET Request

GET Request

GET Request

POST Request

Output Models